home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / man.3 / SplitList.3 < prev    next >
Text File  |  1995-07-17  |  11KB  |  346 lines
  1. '\"
  2. '\" Copyright (c) 1989-1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/tcl/man/RCS/SplitList.3,v 1.11 93/04/01 09:25:34 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .\" The definitions below are for supplemental macros used in Tcl/Tk
  24. .\" manual entries.
  25. .\"
  26. .\" .HS name section [date [version]]
  27. .\"    Replacement for .TH in other man pages.  See below for valid
  28. .\"    section names.
  29. .\"
  30. .\" .AP type name in/out [indent]
  31. .\"    Start paragraph describing an argument to a library procedure.
  32. .\"    type is type of argument (int, etc.), in/out is either "in", "out",
  33. .\"    or "in/out" to describe whether procedure reads or modifies arg,
  34. .\"    and indent is equivalent to second arg of .IP (shouldn't ever be
  35. .\"    needed;  use .AS below instead)
  36. .\"
  37. .\" .AS [type [name]]
  38. .\"    Give maximum sizes of arguments for setting tab stops.  Type and
  39. .\"    name are examples of largest possible arguments that will be passed
  40. .\"    to .AP later.  If args are omitted, default tab stops are used.
  41. .\"
  42. .\" .BS
  43. .\"    Start box enclosure.  From here until next .BE, everything will be
  44. .\"    enclosed in one large box.
  45. .\"
  46. .\" .BE
  47. .\"    End of box enclosure.
  48. .\"
  49. .\" .VS
  50. .\"    Begin vertical sidebar, for use in marking newly-changed parts
  51. .\"    of man pages.
  52. .\"
  53. .\" .VE
  54. .\"    End of vertical sidebar.
  55. .\"
  56. .\" .DS
  57. .\"    Begin an indented unfilled display.
  58. .\"
  59. .\" .DE
  60. .\"    End of indented unfilled display.
  61. .\"
  62. '\"    # Heading for Tcl/Tk man pages
  63. .de HS
  64. .ds ^3 \\0
  65. .if !"\\$3"" .ds ^3 \\$3
  66. .if '\\$2'cmds'       .TH \\$1 1 \\*(^3 \\$4
  67. .if '\\$2'lib'        .TH \\$1 3 \\*(^3 \\$4
  68. .if '\\$2'tcl'        .TH \\$1 n \\*(^3 Tcl "Tcl Built-In Commands"
  69. .if '\\$2'tk'         .TH \\$1 n \\*(^3 Tk "Tk Commands"
  70. .if '\\$2'tclc'        .TH \\$1 3 \\*(^3 Tcl "Tcl Library Procedures"
  71. .if '\\$2'tkc'         .TH \\$1 3 \\*(^3 Tk "Tk Library Procedures"
  72. .if '\\$2'tclcmds'         .TH \\$1 1 \\*(^3 Tk "Tcl Applications"
  73. .if '\\$2'tkcmds'         .TH \\$1 1 \\*(^3 Tk "Tk Applications"
  74. .if t .wh -1.3i ^B
  75. .nr ^l \\n(.l
  76. .ad b
  77. ..
  78. '\"    # Start an argument description
  79. .de AP
  80. .ie !"\\$4"" .TP \\$4
  81. .el \{\
  82. .   ie !"\\$2"" .TP \\n()Cu
  83. .   el          .TP 15
  84. .\}
  85. .ie !"\\$3"" \{\
  86. .ta \\n()Au \\n()Bu
  87. \&\\$1    \\fI\\$2\\fP    (\\$3)
  88. .\".b
  89. .\}
  90. .el \{\
  91. .br
  92. .ie !"\\$2"" \{\
  93. \&\\$1    \\fI\\$2\\fP
  94. .\}
  95. .el \{\
  96. \&\\fI\\$1\\fP
  97. .\}
  98. .\}
  99. ..
  100. '\"    # define tabbing values for .AP
  101. .de AS
  102. .nr )A 10n
  103. .if !"\\$1"" .nr )A \\w'\\$1'u+3n
  104. .nr )B \\n()Au+15n
  105. .\"
  106. .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
  107. .nr )C \\n()Bu+\\w'(in/out)'u+2n
  108. ..
  109. '\"    # BS - start boxed text
  110. '\"    # ^y = starting y location
  111. '\"    # ^b = 1
  112. .de BS
  113. .br
  114. .mk ^y
  115. .nr ^b 1u
  116. .if n .nf
  117. .if n .ti 0
  118. .if n \l'\\n(.lu\(ul'
  119. .if n .fi
  120. ..
  121. '\"    # BE - end boxed text (draw box now)
  122. .de BE
  123. .nf
  124. .ti 0
  125. .mk ^t
  126. .ie n \l'\\n(^lu\(ul'
  127. .el \{\
  128. .\"    Draw four-sided box normally, but don't draw top of
  129. .\"    box if the box started on an earlier page.
  130. .ie !\\n(^b-1 \{\
  131. \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  132. .\}
  133. .el \}\
  134. \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
  135. .\}
  136. .\}
  137. .fi
  138. .br
  139. .nr ^b 0
  140. ..
  141. '\"    # VS - start vertical sidebar
  142. '\"    # ^Y = starting y location
  143. '\"    # ^v = 1 (for troff;  for nroff this doesn't matter)
  144. .de VS
  145. .mk ^Y
  146. .ie n 'mc \s12\(br\s0
  147. .el .nr ^v 1u
  148. ..
  149. '\"    # VE - end of vertical sidebar
  150. .de VE
  151. .ie n 'mc
  152. .el \{\
  153. .ev 2
  154. .nf
  155. .ti 0
  156. .mk ^t
  157. \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
  158. .sp -1
  159. .fi
  160. .ev
  161. .\}
  162. .nr ^v 0
  163. ..
  164. '\"    # Special macro to handle page bottom:  finish off current
  165. '\"    # box/sidebar if in box/sidebar mode, then invoked standard
  166. '\"    # page bottom macro.
  167. .de ^B
  168. .ev 2
  169. 'ti 0
  170. 'nf
  171. .mk ^t
  172. .if \\n(^b \{\
  173. .\"    Draw three-sided box if this is the box's first page,
  174. .\"    draw two sides but no top otherwise.
  175. .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  176. .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
  177. .\}
  178. .if \\n(^v \{\
  179. .nr ^x \\n(^tu+1v-\\n(^Yu
  180. \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
  181. .\}
  182. .bp
  183. 'fi
  184. .ev
  185. .if \\n(^b \{\
  186. .mk ^y
  187. .nr ^b 2
  188. .\}
  189. .if \\n(^v \{\
  190. .mk ^Y
  191. .\}
  192. ..
  193. '\"    # DS - begin display
  194. .de DS
  195. .RS
  196. .nf
  197. .sp
  198. ..
  199. '\"    # DE - end display
  200. .de DE
  201. .fi
  202. .RE
  203. .sp .5
  204. ..
  205. .HS Tcl_SplitList tclc
  206. .BS
  207. .SH NAME
  208. Tcl_SplitList, Tcl_Merge, Tcl_ScanElement, Tcl_ConvertElement \- manipulate Tcl lists
  209. .SH SYNOPSIS
  210. .nf
  211. \fB#include <tcl.h>\fR
  212. .sp
  213. int
  214. \fBTcl_SplitList\fR(\fIinterp, list, argcPtr, argvPtr\fR)
  215. .sp
  216. char *
  217. \fBTcl_Merge\fR(\fIargc, argv\fR)
  218. .sp
  219. int
  220. \fBTcl_ScanElement\fR(\fIsrc, flagsPtr\fR)
  221. .sp
  222. int
  223. \fBTcl_ConvertElement\fR(\fIsrc, dst, flags\fR)
  224. .SH ARGUMENTS
  225. .AS Tcl_Interp ***argvPtr
  226. .AP Tcl_Interp *interp out
  227. Interpreter to use for error reporting.
  228. .AP char *list in
  229. Pointer to a string with proper list structure.
  230. .AP int *argcPtr out
  231. Filled in with number of elements in \fIlist\fR.
  232. .AP char ***argvPtr out
  233. \fI*argvPtr\fR will be filled in with the address of an array of
  234. pointers to the strings that are the extracted elements of \fIlist\fR.
  235. There will be \fI*argcPtr\fR valid entries in the array, followed by
  236. a NULL entry.
  237. .AP int argc in
  238. Number of elements in \fIargv\fR.
  239. .AP char **argv in
  240. Array of strings to merge together into a single list.
  241. Each string will become a separate element of the list.
  242. .AP char *src in
  243. String that is to become an element of a list.
  244. .AP int *flagsPtr in
  245. Pointer to word to fill in with information about \fIsrc\fR.
  246. The value of *\fIflagsPtr\fR must be passed to \fBTcl_ConvertElement\fR.
  247. .AP char *dst in
  248. Place to copy converted list element.  Must contain enough characters
  249. to hold converted string.
  250. .AP int flags in
  251. Information about \fIsrc\fR. Must be value returned by previous
  252. call to \fBTcl_ScanElement\fR, possibly OR-ed
  253. with \fBTCL_DONT_USE_BRACES\fR.
  254. .BE
  255.  
  256. .SH DESCRIPTION
  257. .PP
  258. These procedures may be used to disassemble and reassemble Tcl lists.
  259. \fBTcl_SplitList\fR breaks a list up into its constituent elements,
  260. returning an array of pointers to the elements using
  261. \fIargcPtr\fR and \fIargvPtr\fR.
  262. While extracting the arguments, \fBTcl_SplitList\fR obeys the usual
  263. rules for backslash substitutions and braces.  The area of
  264. memory pointed to by \fI*argvPtr\fR is dynamically allocated;  in
  265. addition to the array of pointers, it
  266. also holds copies of all the list elements.  It is the caller's
  267. responsibility to free up all of this storage by calling
  268. .DS
  269. \fBfree\fR((char *) \fI*argvPtr\fR)
  270. .DE
  271. when the list elements are no longer needed.
  272. .PP
  273. \fBTcl_SplitList\fR normally returns \fBTCL_OK\fR, which means the list was
  274. successfully parsed.
  275. If there was a syntax error in \fIlist\fR, then \fBTCL_ERROR\fR is returned
  276. and \fIinterp->result\fR will point to an error message describing the
  277. problem.
  278. If \fBTCL_ERROR\fR is returned then no memory is allocated and \fI*argvPtr\fR
  279. is not modified.
  280. .PP
  281. \fBTcl_Merge\fR is the inverse of \fBTcl_SplitList\fR:  it
  282. takes a collection of strings given by \fIargc\fR
  283. and \fIargv\fR and generates a result string
  284. that has proper list structure.
  285. This means that commands like \fBindex\fR may be used to
  286. extract the original elements again.
  287. In addition, if the result of \fBTcl_Merge\fR is passed to \fBTcl_Eval\fR,
  288. it will be parsed into \fIargc\fR words whose values will
  289. be the same as the \fIargv\fR strings passed to \fBTcl_Merge\fR.
  290. \fBTcl_Merge\fR will modify the list elements with braces and/or
  291. backslashes in order to produce proper Tcl list structure.
  292. The result string is dynamically allocated
  293. using \fBmalloc()\fR;  the caller must eventually release the space
  294. using \fBfree()\fR.
  295. .PP
  296. If the result of \fBTcl_Merge\fR is passed to \fBTcl_SplitList\fR,
  297. the elements returned by \fBTcl_SplitList\fR will be identical to
  298. those passed into \fBTcl_Merge\fR.
  299. However, the converse is not true:  if \fBTcl_SplitList\fR
  300. is passed a given string, and the resulting \fIargc\fR and
  301. \fIargv\fR are passed to \fBTcl_Merge\fR, the resulting string
  302. may not be the same as the original string passed to \fBTcl_SplitList\fR.
  303. This is because \fBTcl_Merge\fR may use backslashes and braces
  304. differently than the original string.
  305. .PP
  306. \fBTcl_ScanElement\fR and \fBTcl_ConvertElement\fR are the
  307. procedures that do all of the real work of \fBTcl_Merge\fR.
  308. \fBTcl_ScanElement\fR scans its \fIsrc\fR argument
  309. and determines how to use backslashes and braces
  310. when converting it to a list element.
  311. It returns an overestimate of the number of characters
  312. required to represent \fIsrc\fR as a list element, and
  313. it stores information in \fI*flagsPtr\fR that is needed
  314. by \fBTcl_ConvertElement\fR.
  315. .PP
  316. \fBTcl_ConvertElement\fR is a companion procedure to \fBTcl_ScanElement\fR.
  317. It does the actual work of converting a string to a list element.
  318. Its \fIflags\fR argument must be the same as the value returned
  319. by \fBTcl_ScanElement\fR.
  320. \fBTcl_ConvertElement\fR writes a proper list element to memory
  321. starting at *\fIdst\fR and returns a count of the total number
  322. of characters written, which will be no more than the result
  323. returned by \fBTcl_ScanElement\fR.
  324. \fBTcl_ConvertElement\fR writes out only the actual list element
  325. without any leading or trailing spaces: it is up to the caller to
  326. include spaces between adjacent list elements.
  327. .PP
  328. \fBTcl_ConvertElement\fR uses one of two different approaches to
  329. handle the special characters in \fIsrc\fR.  Wherever possible, it
  330. handles special characters by surrounding the string with braces.
  331. This produces clean-looking output, but can't be used in some situations,
  332. such as when \fIsrc\fR contains unmatched braces.
  333. In these situations, \fBTcl_ConvertElement\fR handles special
  334. characters by generating backslash sequences for them.
  335. The caller may insist on the second approach by OR-ing the
  336. flag value returned by \fBTcl_ScanElement\fR with
  337. \fBTCL_DONT_USE_BRACES\fR.
  338. Although this will produce an uglier result, it is useful in some
  339. special situations, such as when \fBTcl_ConvertElement\fR is being
  340. used to generate a portion of an argument for a Tcl command.
  341. In this case, surrounding \fIsrc\fR with curly braces would cause
  342. the command not to be parsed correctly.
  343.  
  344. .SH KEYWORDS
  345. backslash, convert, element, list, merge, split, strings
  346.